<html>
  <head>
    <title>org.toryt_II.testobject</title>
  </head>

  <body>
    <table>
      <tr><td>$Revision: 188 $</td></tr>
      <tr><td>$Date: 2006-04-26 13:50:11 +0000 (Wed, 26 Apr 2006) $</td></tr>
      <tr><td>$State$</td></tr>
      <tr><td>$Name$</td></tr>
    </table>
    <p>API for test object generation. Test objects are the actual instances
      that are used by a test to execute a method-under-test to validate a
      contract. Tests validate a contract of a method in a particular case.
      A case is a configuration of test objects.</p>
    <p>Test objects are generated for a particular test instance fresh,
      by a {@link org.toryt_II.testobject.TestObjectGenerator}. When
      test objects are of a class that is guaranteed to be immutable,
      the same instance can be used for multiple tests.</p>
    <p>Test object generators for a given class are offered by a
      <dfn>Test Object Factory Priority List</dfn> or
      <acronym title="Test Object Factory Priority List">TOF PL</acronym>.
      When a <acronym title="Test Object Factory Priority List">TOF PL</acronym>
      for a particular class is needed, it should be retrieved
      via the static methods in {@link org.toryt.testobject.TofPlFactory}.
      Toryt offers <acronym title="Test Object Factory Priority List">TOF PL</acronym>s
      for primitive types and most interesting types provided by the standard Java API.
      <acronym title="Test Object Factory Priority List">TOF PL</acronym>s for other
      types are retrieved automatically via naming conventions, or can be registered to
      {@link org.toryt.testobject.TofPlFactory} by hand.</p>
    <h1>Guidelines for <acronym title="Test Object Factory Priority List">TOF PL</acronym>s</h1>
    <p><acronym title="Test Object Factory Priority List">TOF PL</acronym>s
      have {@link org.toryt_II.testobject.TestObjectFactory TestObjectFactories}
      with different priority. When you create a
      <acronym title="Test Object Factory Priority List">TOF PL</acronym>, you should
      follow the following guidelines:</p>
    <ul>
      <li>Never include a {@link org.toryt_II.testobject.TestObjectFactory TestObjectFactories}
        that returns <code>null</code>. <code>null</code> will be added with the highest
        priority by the framework when applicable.</li>
      <li>The bucket for <em>priority 0</em> should return a limited number of
        <dfn>mundane objects</dfn> of the class the
        <acronym title="Test Object Factory Priority List">TOF PL</acronym>
        works for.<br />
        For <em>enumeration types</em>, this should be an exhaustive collection
        of all possible values, and there should be no other priority buckets.<br />
        For non-enumeration types, in general, the priority 0 bucket should be a
        singleton generating 1 mundane case, that is non-special in most uses. E.g., for
        dates, <em>now</em> is a rather special case, and should not be used. For
        some classes, this can be more than 1 factory, e.g., when the type to create
        test objects for is multi-dimensional or has a clear bifurcation. E.g., for
        integers, the priority bucket could contain 1 mundane negative and 1 mundane
        positive number, but not zero, or the maximum or minimum integer.</li>
      <li>The bucket for <em>priority 1</em> should return a limited number of
        <dfn>true border values</dfn>. Implementation bugs often happen with
        border values, so a precise, exhaustive inclusion of the border values
        is important for the quality of the validation. The concept of border values
        is often only applicable to value classes.
        Only include the true border cases in this bucket. For integers, e.g.,
        zero, the minimum and maximum integer are the only true border values.
        For Strings, the true border values are the empty String, and a String
        with maximum length.</li>
      <li>The <acronym title="Test Object Factory Priority List">TOF PL</acronym>
        may contain buckets with <em>priority 2 and higher</em> that contain
        <dfn>special objects</dfn>, with decreasing importance. It is good practice
        to keep the number of
        {@link org.toryt_II.testobject.TestObjectFactory TestObjectFactories}
        in a bucket rather small, and to divide the special objects over several
        buckets with decreasing priorities. Examples of special objects are
        Strings with and without spaces, and with capitals and non-ASCII
        characters. Examples of special longs are the minimum and maximum
        integers, the long 1 larger and 1 smaller than the minimum and maximum
        long respectively, and often used magic numbers such as -1.</li>
    </ul>
    <p>For some classes, some buckets might be empty.</p>
    <p>Bear in mind that test cases are generated by combining test objects.
      Combining several priority lists creates an extremely large priority
      list very quickly (combinatorial explosion). Thus, the
      <acronym title="Test Object Factory Priority List">TOF PL</acronym>s
      for basic types should be kept small, to avoid gigantic numbers of
      of test cases. Don't overdo it: more than the minimal number of mundane
      cases does not make for higher quality validation. It is important though
      to have all border cases in the
      <acronym title="Test Object Factory Priority List">TOF PL</acronym>s.</p>
    <p>General <acronym title="Test Object Factory Priority List">TOF PL</acronym>
      are used to generate cases for methods if no other cases are defined for
      the tests for that method. For a particular method, specific border objects and
      special objects can be added, or the default
      <acronym title="Test Object Factory Priority List">TOF PL</acronym>
      can be replaced entirely. It thus makes no sense to add border objects and
      special objects that are only relevant in extreme cases, since these will
      be used for most methods, where they are not relevant. This would increase
      the number of test cases for those methods astronomically, and make testing
      unwieldly.</p>
      <h2>Overview</h2>
    <table>
      <tr>
        <th>Priority level</th>
        <th>Guideline</th>
      </tr>
      <tr>
        <td>0</td>
        <td>mundane objects, 1 if possible</td>
      </tr>
      <tr>
        <td>1</td>
        <td>true border objects; very limited</td>
      </tr>
      <tr>
        <td>2</td>
        <td rowspan="4">special objects</td>
      </tr>
      <tr>
        <td>3</td>
      </tr>
      <tr>
        <td>4</td>
      </tr>
      <tr>
        <td>...</td>
      </tr>
    </table>
  </body>

</html>